2021.1 (latest)

Integrations

On this page:

Policy Manager Entities

Policy Manager Entities

Policy Manager entities come in several different varieties, two of which integration developers must be prepared to deal with.

The document structures stored in the database are internal to Policy Manager, and are transformed on import and on export through an integration.

When Policy Manager provides template results to your integration's import function, it expects a minimal Policy Manager entity representation to return back. This representation abbreviates several fields which are summarized below.

When Policy Manager provides policy entities to the prerender method, it expands all referenced network and rule entities into the policy, resulting in an expanded Policy Manager policy entity.

Below is a description of the standard, internal Policy Manager entity structure. Following this are two sections describing the difference between the standard format and both the minimal import and expanded export formats.

Standard Policy Manager Entities

Policy Manager defines five main types of entities with which device integrations must interact:

  1. Targets
  2. Policies
  3. Rules
  4. Networks
  5. Services

Targets

Policy Manager target entities are used to represent device resources such as network interfaces which may have an access list attached to them.

Each target must have the following properties:

Property Description
name The name of the target.
addressType Either IPv4 or IPv6.
sourceNetworks An array of network strings utilizing CIDR notation.
destinationNetworks An array of network strings utilizing CIDR notation.
policyReference Either a Mongo ObjectId linking the target to a policy entity, or null.

Note: Whereas policy entities reference a network document in their rules using an ObjectId, target entities list the address string on its own.

Example Target Entity

{
  "id" : "d07bf296-0f62-4517-a0e8-3cc35d34bab6",
  "name" : "GigabitEthernet1_in",
  "addressType" : "IPv4",
  "sourceNetworks" : [
    "10.1.3.198/24"
  ],
  "destinationNetworks" : [
    "0.0.0.0/0"
  ],
  "policyReference" : null
}

Policies

Policy Manager policy entities are used to represent ACL configuration in a device-agnostic format.

Each policy has the following properties:

Property Description
name The name of the policy.
policyType Either IPv4 or IPv6.
rules An array of rule entities, describing individual lines of ACL configuration.
description Optional. A textual description of the policy.

There are several other properties which are automatically added to policy entities by Policy Manager, but these are internally managed and have no bearing on the data represented by the policy.

Example Policy Entity

{
  "_id" : ObjectId("5defe445df7e6487cf63719f"),
  "description" : "Policy imported from device 'csr01-aws-ansible'",
  "policyType" : "acl",
  "addressType" : "IPv4",
  "rules" : [
    {
      "name" : "pm-test-ext-1_rule0",
      "description" : "Rule imported from device 'csr01-aws-ansible', policy pm-test-ext-1",
      "action" : "permit",
      "enabled" : true,
      "policyType" : "acl",
      "sourceNetworks" : [
        ObjectId("5defe445df7e6487cf63712b")
      ],
      "destinationNetworks" : [
        ObjectId("5defe445df7e6487cf63712b")
      ],
      "services" : [
        ObjectId("5defe445df7e6487cf637164")
      ],
      "templates" : [],
      "logging" : false,
      "flags" : null,
      "serviceNumber" : null,
      "id" : "58b443ff-8715-46cf-b7d9-0fcc34c0a43f",
      "templateReference" : null
    },
    {
      "id" : "91d1d443-13e4-40db-9591-223bd387bd8a",
      "name" : "pm-test-ext-1_rule1",
      "description" : "Rule imported from device 'csr01-aws-ansible', policy pm-test-ext-1",
      "policyType" : "acl",
      "action" : "permit",
      "logging" : false,
      "sourceNetworks" : [
        ObjectId("5defe445df7e6487cf63712b")
      ],
      "destinationNetworks" : [
        ObjectId("5defe445df7e6487cf63712b")
      ],
      "services" : [
        ObjectId("5defe445df7e6487cf637143")
      ],
      "templateReference" : null,
      "enabled" : true
    }
  ],
  "schemaVersion" : 2,
  "name" : "pm-test-ext-1",
  "created" : ISODate("2019-12-10T18:30:29.175Z"),
  "createdBy" : ObjectId("5d5ee09698d228c1b3bf360a"),
  "lastUpdated" : ISODate("2019-12-10T19:16:27.925Z"),
  "lastUpdatedBy" : ObjectId("5d5ee09698d228c1b3bf360a")
}

Rules

Rule entities in Policy Manager model individual lines of ACL configuration.

Rules have the following properties:

Property Description
name The name of the rule.
policyType Only rules with 'acl' for policyType are supported.
action This property is set to 'permit' or 'deny'.
logging Boolean: true or false. This property is expected to be translated to a least-common-denominator form of logging during export. Devices with extensive logging options must be exported in such a way that logging behaves as a simple yes/no attribute.
sourceNetworks An array of ObjectIds relating this rule entity to network entities.
destinationNetworks An array of ObjectIds relating this rule entity to network entities.
services An array of ObjectIds relating this rule entity to service entities.
enabled Boolean: true or false. Disabled rules should not be exported.
description Optional. A string describing the rule.

Example Rule Entity

{
  "name" : "pm-test-ext-1_rule0",
  "description" : "Rule imported from device 'csr01-aws-ansible', policy pm-test-ext-1",
  "action" : "permit",
  "enabled" : true,
  "policyType" : "acl",
  "sourceNetworks" : [
    ObjectId("5defe445df7e6487cf63712b")
  ],
  "destinationNetworks" : [
    ObjectId("5defe445df7e6487cf63712b")
  ],
  "services" : [
    ObjectId("5defe445df7e6487cf637164")
  ],
  "templates" : [],
  "logging" : false,
  "flags" : null,
  "serviceNumber" : null,
  "id" : "58b443ff-8715-46cf-b7d9-0fcc34c0a43f",
  "templateReference" : null
}

Networks

Policy Manager network entities are used to store several fields related to networks. Policy Manager validates and completes network entities using Policy Engine.

Each network has the following properties:

Property Description
name The name of the network.
description Optional. A description of the network.
addressType Either IPv4 or IPv6.
canonical The full address written in CIDR notation.
address The address portion of the canonical representation.
prefixLength The prefix portion of the canonical representation.
netmask The netmask calculated from the CIDR prefix length.
hostmask The hostmask calculated from the CIDR prefix length.

Example Network Entity

{
  "_id" : ObjectId("5defe445df7e6487cf63712a"),
  "name" : "10.1.0.0/24",
  "description" : "Network imported from policy '1'",
  "addressType" : "IPv4",
  "canonical" : "10.1.0.0/24",
  "address" : "10.1.0.0",
  "prefixLength" : 24,
  "netmask" : "255.255.255.0",
  "hostmask" : "0.0.0.255",
  "created" : ISODate("2019-12-10T18:30:29.175Z"),
  "createdBy" : ObjectId("5d5ee09698d228c1b3bf360a"),
  "lastUpdated" : ISODate("2019-12-10T18:30:29.175Z"),
  "lastUpdatedBy" : ObjectId("5d5ee09698d228c1b3bf360a"),
  "schemaVersion" : 2
}

Services

Policy Manager service entities are used to represent a set of attributes to be used as traffic matching or traffic filtering configuration attributes in ACL rule configuration.

Each service entity has the following properties:

Property Description
name The name of the service.
description Optional. A description field.
traffic An object, which must conform to several requirements which are delineated below.

The traffic property in a service entity is used to store information pertinent to traffic matching and restriction. Each traffic object must contain a protocol property, which stores the standard numeric representation of a protocol. See the IANA protocol registry for a list of protocols and their assigned numbers. The rest of the properties in the traffic object depend on the value of 'protocol'.

The following is a list of options available to each protocol. Cross-reference these options with the next list, which describes the structure and meaning of each property referenced below.

Traffic options by protocol:

Option Description
Common Any traffic object for a protocol built on top of IPv4 or IPv6 may use the properties: 'timeout', 'ttl', 'dscp', 'tos', and 'fragmentOptions'.
ICMP [1] An ICMP traffic object may have the property 'typecodes'.
TCP [6] A TCP traffic object may have the properties: 'sourcePort', 'destinationPort', and 'controlFlags'.
UDP [17] An UDP traffic object may have the properties: 'sourcePort', and 'destinationPort'.
ICMPv6 [58] An IPv6-ICMP traffic object may have the property 'typecodes'.

Structure and meaning of various traffic options:

  • sourcePort/destinationPort

    Both of these properties have the same structure, and express the same intent. They are used to represent a matching expression for one or more ports on either the source or destination of a given packet. Several operator options are used to express their restriction:

    • Range: { "range": ["22", "80"] }

      Range is used to express an inclusive interval of port numbers to match on.

    • One of: { "oneOf": ["22", "23", "24"] }

      One of is used to match when the given port number is included in the stored list of port numbers.

    • Not: { "not": ["100", "102"] }

      Not is used to match when the given port number is not included in the stored list of port numbers.

    • Less than: { "lessThan": "81" }

      Less than is used to match when the given port number is less than the stored port number.

    • Greater than: { "greaterThan": "81" }

      Greater than is used to match when the given port number is greater than the stored port number.

  • timeout

    Timeout is used to match against the timeout header field of the incoming packet. It must be an integer greater than 0, and as with the IP timeout field, it uses seconds as its unit of measurement.

  • ttl

    TTL is used to match against the time-to-live header field of the incoming packet. Time to live uses the same numeric range operators listed above for port numbers.

  • dscp

    DSCP is used to match against the differentiated-services-code-point header field of the incoming packet. It may have an integer value from 0 to 63.

  • tos

    TOS is used to match against the type-of-service header field in the incoming packet. It must be an object with the following fields:

    • precedence: An integer from 0 to 7, denoting the precedence value of the TOS field.
    • lowDelay: A boolean denoting the low-delay bit of the TOS field.
    • highThroughput: A boolean denoting the high-throughput bit of the TOS field.
    • highReliability: A boolean denoting the high-reliability bit of the TOS field.
    • minimizeCost: A boolean denoting the minimize-cost bit of the TOS field.

  • fragmentOptions

    Fragment options are used to specify matching and filtering on the fragments header field of incoming traffic. Fragment options will be a list of items describing either one 'include' or one 'exclude' operation.

    Example: { "fragmentOptions": [{ "exclude": "first" }, { "include": "last" }] }
The available operation parameters are: 'first', 'last', and 'all'
'first' will match the first packet in a fragmented sequence.
'last' will match the last packet in a fragmented sequence.
'all' will match any fragmented packet. Inverting 'all' using { "exclude": "all" } will allow only non-fragmented traffic.

  • typecodes

    Typecodes are used to represent the typecode field provided by ICMP and IPv6-ICMP. Each typecode is composed of a pair of integers, one representing the overall type, and the other, the code, denoting which message or sub-type to match.

    The typecodes property must be an array, and must have items adhering to the following structure:

    {
  "type": "An integer denoting the type",
  "code": "Either an integer denoting the code, or null, either for matching a type on its own, or for types without codes"
}

    There are very specific requirements for typecodes, and the typecodes for IPv4 ICMP and IPv6-ICMP are different. Use the IANA documentation for more information on ICMP typecodes and IPv6-ICMP typecodes.

  • controlFlags

    Control flags are used to match against the control bits available in TCP headers. The field must contain an array whose elements each denote a flag state to match against. Flags which are not included in the array are ignored.

    Available flags: ns, ece, urg, ack, psh, rst, cwr, syn, fin

    The following example will apply to TCP traffic with control bits matching the pattern: 1xxxx01xx

    {
      "controlFlags": [
        { "ns": true },
        { "psh": false },
        { "rst": true }
      ]
    }

Example Service Entity

{
  "_id" : ObjectId("5defe445df7e6487cf637145"),
  "name" : "tcp_ISPacl1be10iosxr",
  "description" : "Service imported from policy 'ISPacl1be10iosxr'",
  "traffic" : {
    "protocol" : 6,
    "sourcePort" : {
      "oneOf" : [
        "22"
      ]
    },
    "destinationPort" : {
      "range" : [
        "1024",
        "65535"
      ]
    },
    "controlFlags" : {
      "allOf" : [
        {
          "ack" : true
        }
      ]
    }
  },
  "created" : ISODate("2019-12-10T18:30:29.175Z"),
  "createdBy" : ObjectId("5d5ee09698d228c1b3bf360a"),
  "lastUpdated" : ISODate("2019-12-10T18:30:29.175Z"),
  "lastUpdatedBy" : ObjectId("5d5ee09698d228c1b3bf360a"),
  "schemaVersion" : 2
}

Minimal Representation in Policy Manager

The minimal representation that is expected for Policy Manager entities from the integration's import method is described below.

Targets

The minimal representation of targets uses a 'policy' field instead of a 'policyReference' field. The 'policy' field is the name of the policy to use for the target, whereas the 'policyReference' field is an ObjectId referencing the completed policy entity after Policy Manager has created it.

Policies

The minimal representation of policies uses a minimal version of rules inside the rules array. The source and destination networks array in a minimal rule entity that contains minimal network entities instead of reference ids. The services array contains minimal service entities instead of reference ids.

Networks

A minimal network entity is a string containing the CIDR representation of the network.

Services

A minimal service entity is the same as a standard service entity, but without the fields added internally by Policy Manager: 'created', 'createdBy', 'lastUpdated', 'lastUpdatedBy', 'schemaVersion', and '_id'

Expanded Representation of Policy Manager Entities

The only entity type that expansion affects is the policy entity. Before passing a policy into your preRenderPolicy function, Policy Manager will dereference all fields which are ids referencing other entities, such as networks and services in rules.

Example Expanded Policy

{
  "id": "5df3d04ccded45c06ab274fd",
  "description": "Policy imported from device 'csr01-aws-ansible'",
  "policyType": "acl",
  "addressType": "IPv4",
  "rules": [
    {
      "name": "pm-test-ext-1_rule0",
      "description": "Rule imported from device 'csr01-aws-ansible', policy pm-test-ext-1",
      "action": "permit",
      "policyType": "acl",
      "logging": true,
      "templateReference": null,
      "id": "8a667a2f-112a-411e-bc04-4593ef39fef3",
      "enabled": true,
      "sourceNetworks": [
        {
          "id": "5df3d04ccded45c06ab27489",
          "name": "0.0.0.0/0",
          "addressType": "IPv4",
          "canonical": "0.0.0.0/0",
          "address": "0.0.0.0",
          "prefixLength": 0,
          "netmask": "0.0.0.0",
          "hostmask": "255.255.255.255",
          "schemaVersion": 2
        }
      ],
      "destinationNetworks": [
        {
          "id": "5df3d04ccded45c06ab27489",
          "name": "0.0.0.0/0",
          "addressType": "IPv4",
          "canonical": "0.0.0.0/0",
          "address": "0.0.0.0",
          "prefixLength": 0,
          "netmask": "0.0.0.0",
          "hostmask": "255.255.255.255",
          "schemaVersion": 2
        }
      ],
      "services": [
        {
          "id": "5df3d04ccded45c06ab274c2",
          "name": "tcp_pm-test-ext-1",
          "traffic": {
            "protocol": 6
          },
          "schemaVersion": 2
        }
      ]
    },
    {
      "name": "pm-test-ext-1_rule1",
      "description": "Rule imported from device 'csr01-aws-ansible', policy pm-test-ext-1",
      "action": "permit",
      "policyType": "acl",
      "logging": false,
      "templateReference": null,
      "id": "b593ccaf-9729-4e02-9a4b-7881a6b81450",
      "enabled": true,
      "sourceNetworks": [
        {
          "id": "5df3d04ccded45c06ab27489",
          "name": "0.0.0.0/0",
          "addressType": "IPv4",
          "canonical": "0.0.0.0/0",
          "address": "0.0.0.0",
          "prefixLength": 0,
          "netmask": "0.0.0.0",
          "hostmask": "255.255.255.255",
          "schemaVersion": 2
        }
      ],
      "destinationNetworks": [
        {
          "id": "5df3d04ccded45c06ab27489",
          "name": "0.0.0.0/0",
          "addressType": "IPv4",
          "canonical": "0.0.0.0/0",
          "address": "0.0.0.0",
          "prefixLength": 0,
          "netmask": "0.0.0.0",
          "hostmask": "255.255.255.255",
          "schemaVersion": 2
        }
      ],
      "services": [
        {
          "id": "5df3d04ccded45c06ab274a1",
          "name": "icmp_ISPacl1be10iosxr",
          "traffic": {
            "protocol": 1
          },
          "schemaVersion": 2
        }
      ]
    }
  ],
  "schemaVersion": 2,
  "name": "pm-test-ext-1",
  "created": "2019-12-13T17:55:04.642Z",
  "createdBy": "admin@pronghorn",
  "lastUpdated": "2019-12-13T17:55:04.642Z",
  "lastUpdatedBy": "admin@pronghorn"
}